Modules/BRL/Blitz
BRL.Blitz is the main module for BlitzMax, and is included into every application. NOTE: EndFunction, EndWhile, EndMethod, EndIf, ElseIf, EndRem, EndSelect, EndExtern and EndTry can also be written with the two words separated. Example: Rem Comment block! End Rem Function MyFunction() End Function ' etc.. =Globals= AppDir Global AppDir:String Description: Application directory. Information: The AppDir global variable contains the full directory of the currently executing application. An application's initial current directory is also set to AppDir when an application starts. Example: Print(AppDir) AppFile Global AppFile:String Description: Application file. Information: The AppFile global variable contains the full file path of the currently executing application. Example: Print(AppFile) AppTitle Global AppTitle:String Description: Application title. Information: The AppTitle global variable is used by various commands when a default application title is required - for example, when opening simple windows or requesters. Initially, AppTitle is set the value "BlitzMax Application". However, you may change AppTitle at any time with a simple assignment. NOTE: AppTitle'' is used as the title of a graphics window. Example: Print(AppTitle) ' Default is "BlitzMax Application" AppTitle = "My Application Title!" AppArgs Global AppArgs:String[] '''Description: Arguments passed to the application at startup. Information: The AppArgs global array contains the command line parameters sent to an application when it was started. The first element of AppArgs always contains the name of the application. However, the format of the name may change depending on how the application was launched. Use AppDir' or AppFile for consistent information about the application's name or directory. Example: Local index:Int ' We want to ignore the first element If AppArgs.Length > 1 For index = 1 To AppArgs.Length - 1 Print("Application argument: " + AppArgsindex) Next End If LaunchDir ''Global LaunchDir:String Description: The directory from which the application was launched. Information: The LaunchDir global variable contains the current directory at the time the application was launched. This is mostly of use to command line tools which may need to access the shell's current directory as opposed to the application directory (AppDir). Example: Print(LaunchDir) =Constants= True Const True:Int Description: Constant integer value equaling 1'. Example: Print("True = " + True) If True Print("This line will always execute") End If If Not True Print("This line will never execute") End If False ''Const False:Int '''Description: Constant integer value equaling 0'. Example: Print("False = " + False) If False Print("This line will never execute") End If Pi ''Const Pi:Double '''Description: Constant double value equaling 3.1415926535897932384626433832795. Example: Print("Pi = " + Pi) Null Internal constant Null Description: Empty object reference. Example: Type TMyType Field integer:Int = 100 End Type Local obj:TMyType If obj = Null Print("obj has not been initialized") obj = New TMyType If obj <> Null Print("obj is initialized") =Keywords= Strict Description: Set Strict coding mode. Information: With the Strict mode enabled, variables cannot be defined without a preceding Local, Const or Global keyword. Labels are not allowed in Strict (except for DefData labels). NOTE: In Strict mode return types/variables/parameters have automatic data typing when set. The default data type for variables is Int. Example: Local a = 10 b = 20 ' Fails to compile because identifiers must be defined before use SuperStrict Description: Set SuperStrict coding mode. Information: With the SuperStrict mode enabled, all variables (constants, globals, locals, fields, parameters, etc.), all Functions and Methods (parameters and return types) must define a data type. Labels are not allowed in SuperStrict (except for DefData labels). Example: SuperStrict Local myint:Int, myfloat:Float Local myint ' Fails to compile because datatype is missing (there is no default data type like in Strict) End Description: End the application. Example: Print("Hello!") End Print("Goodbye?") ' Program ends before this can be executed Rem ... EndRem Description: Mutli-line comment block. Example: Rem Multi-line comment blocks! How useful! EndRem Data types Byte Short Int Long Float Double String Object Var, Ptr, VarPtr, SizeOf If, Then, ElseIf, Else, EndIf For, To, Eachin, Step, Next While, Wend, EndWhile Repeat, Until, Forever Select, Case, Default, EndSelect Exit, Continue Local, Global, Const Function ... EndFunction Return Description: Return from a function or a method. Example: Print(MyFunction()) Function MyFunction:Int() Return 10 End Function MyFunction2(100) Function MyFunction2(value:Int) If value = 100 Return ' Return to the main program without returning any value End If Print("value = " + value) End Function Type, Field, Self, Super, Final, New, Abstract, Extends, EndType Method ... EndMethod Release KEYWORD Description: Information: Example: Public, Private Extern ... EndExtern Module, ModuleInfo Incbin, IncbinPtr, IncbinLen Framework, Import, Include Goto Goto Description: Go to the specified label. Information: Evil. Avoid at all costs. Note: Goto does not work in SuperStrict or Strict mode. Also, labels are limited to DefData in either Strict or SuperStrict mode. Example: Print("One") Goto somewhere Print("Not executed") #somewhere Print("Hello, cruel world!") Try, Catch, EndTry A Try ... Catch ... EndTry block attempts to catch an exception that might have been thrown between Try and Catch, and attempts to handle the exception (instead of ending the program). Example: For Local index:Int = 0 To 4 Try MyFunction(index) Catch e:Object ' Strings are actually objects, so we can account for all types of possible exceptions by ' making the caught variable an Object and calling ToString on it. Print("Caught exception: " + e.ToString()) EndTry Next Function MyFunction(index:Int) If index = 2 Throw "I don't like the number 2!" End If Print("index = " + index) End Function Throw Description: Throw an exception (can be any object). Example: Throw "Error!" Assert Description: Assert is the same as Throw, except that it only gets compiled in Debug mode (useful for debugging-only purposes), and that it is a conditional wrapper. Information: If the given condition/expression evaluates to a non-value (False or Null), the exception will be thrown. Example: ' In debug mode, an assert will be thrown, but in Release mode, the program will continue on without a stop Local MyInteger:Int = 8 ' There are two ways to write an Assert, either: Assert MyInteger = 10, "MyInteger must equal 10!" ' Or this (using Else instead of a comma): 'Assert MyInteger = 10 Else "MyInteger must equal 10!" DefData, ReadData, RestoreData And, Or, Not, Shl, Shr, Sar Len KEYWORD Description: Information: Example: Abs KEYWORD Description: Information: Example: Mod KEYWORD Description: Information: Example: Sgn KEYWORD Description: Information: Example: Min, Max KEYWORD Description: Information: Example: =Functions= RuntimeError Function RuntimeError(error:String) Description: Throw a runtime error. Information: This will Throw a TRuntimeException with the given error string. Example: Local MyInteger:Int = 9 If MyInteger <> 10 RuntimeError("MyInteger <> 10!!") End If DebugStop, DebugLog OnEnd Description: Add a function to be called when the program ends. Information: Functions added are called in the reverse order to that in which they were added. Example: OnEnd(MyFunction) End Function MyFunction() Print("Bye!") End Function ReadStdin, WriteStdout, WriteStderr Delay, MilliSecs MemAlloc, MemFree, MemExtend, MemClear, MemCopy, MemMove GCSetMode, GCSuspend, GCResume, GCCollect, GCMemAlloced, GCEnter, GCLeave HandleFromObject, HandleToObject Function HandleFromObject:Int(obj:Object) Description: Convert the given object to an integer handle (not a pointer). Returns: The integer handle for the given object. Information: After converting an object to an integer handle, you must later release it using the Release command. Function HandleToObject:Object(handle:Int) Description: Convert the given integer handle to an object. Returns: The object for the given handle. Example (of both functions): Type TMyType Field myfield:Int = 100 End Type Local obj:TMyType = New TMyType, objhandle:Int objhandle = HandleFromObject(obj) Print(objhandle) Local obj2:TMyType obj2 = TMyType(HandleToObject(objhandle)) ' Cast the object back to a TMyType If obj = obj2 Print("Matches!") End If Print(obj2.myfield)